feat(external-agents): add crate foundation for CLI agent bridge#566
Open
feat(external-agents): add crate foundation for CLI agent bridge#566
Conversation
Introduce `crates/external-agents/` with core types, traits, and session bridge logic for connecting Moltis chat sessions to external CLI coding agents (Claude Code, opencode, Codex, Pi agent, ACP). New crate provides: - `ExternalAgentTransport` / `ExternalAgentSession` traits - `ExternalAgentRegistry` for runtime dispatch - Delta sync engine with compaction reconciliation (4 scenarios) - Feature-gated runtime stubs for 5 agent kinds - `ExternalAgentError` with thiserror Wires into existing workspace: - `ExternalAgentsConfig` added to `MoltisConfig` schema - `build_schema_map()` and config template updated - `ExternalAgentService` trait + noop added to `Services` bundle - `external_agent_kind` / `external_session_id` on `SessionEntry` Entire-Checkpoint: 3e13cf1c768d
Contributor
Merging this PR will not alter performance
Comparing 
Footnotes
|
Contributor
Greptile SummaryIntroduces the Confidence Score: 5/5Safe to merge — all findings are P2 style and maintenance suggestions with no current defects All five concerns from prior review rounds have been addressed: no Other catch-all in error.rs, tracing instrumented on runtimes, synced_message_count naming corrected, ExternalAgentKind is a typed mirror enum, unused moltis-agents dep removed. Remaining findings are a missing semantic validation rule per CLAUDE.md and a future migration hygiene note — neither blocks merge. crates/config/src/validate.rs (semantic warning for unknown agent-kind keys); crates/sessions/src/metadata.rs (From will need updating when DB migration lands) Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Chat Session] -->|send prompt| B[ExternalAgentRegistry]
B -->|lookup AgentTransportKind| C{Transport Found?}
C -- No --> D[NoRuntimeForKind error]
C -- Yes --> E[ExternalAgentTransport::start_session]
E --> F[ExternalAgentSession]
F --> G[compute_delta]
G --> H{BridgeState.initialized?}
H -- No --> I[Full context snapshot\nstart_index=0]
H -- Yes --> J{CLI alive?}
J -- No --> K[CliCompacted\nsnapshot=true]
J -- Yes --> L{count < synced_message_count?}
L -- Yes --> M[MoltisCompacted\nsnapshot=true]
L -- No --> N{hash mismatch at tail?}
N -- Yes --> M
N -- No --> O[Delta sync\nstart_index=synced_message_count]
I --> P[send_prompt + ContextSnapshot]
O --> P
P --> Q[Stream ExternalAgentEvent]
Q --> R[advance_bridge_state]
R --> S[Update synced_message_count\n+ last_synced_tail_hash]
Reviews (6): Last reviewed commit: "fix(external-agents): typed enum for ses..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
- Remove unused `moltis-agents` dependency - Rename `last_synced_message_index` → `synced_message_count` (stores a count, not a 0-based index) - Replace `Other(#[from] anyhow::Error)` catch-all with concrete `ProcessSpawn` and `Protocol` variants - Add `#[tracing::instrument]` on registry async methods (feature-gated) - Document `external_agent_kind: Option<String>` as a serialization boundary (sessions crate has no dep on external-agents) Entire-Checkpoint: 433a46b5f3fb
- Replace `external_agent_kind: Option<String>` with typed `Option<ExternalAgentKind>` enum in SessionEntry (mirror enum in moltis-sessions to avoid cross-crate dep) - Export `ExternalAgentKind` from moltis-sessions - Add `#[tracing::instrument]` (feature-gated) to all runtime transport `is_available` and `start_session` methods Entire-Checkpoint: 016437bf01ff
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
crates/external-agents/— new workspace crate for connecting Moltis chat sessions to external CLI coding agents (Claude Code, opencode, Codex CLI, Pi agent, ACP)AgentTransportKind,ExternalAgentEvent,ContextSnapshot,BridgeState), transport traits (ExternalAgentTransport,ExternalAgentSession), registry for runtime dispatch, and delta sync engine with compaction reconciliationExternalAgentsConfigin config schema/validate/template,ExternalAgentServicetrait in service-traitsServicesbundle,external_agent_kind/external_session_idonSessionEntryValidation
Completed
cargo check --workspace— cleancargo +nightly-2025-11-30 fmt --all -- --check— cleancargo clippy -p moltis-external-agents --all-targets -- -D warnings— cleantaplo fmt— cleanRemaining
./scripts/local-validate.sh <PR_NUMBER>— full validation suitejust test— full workspace test suiteManual QA
This is Phase 1 (foundation only) — no user-visible behavior changes yet. Runtime stubs return "not yet implemented" errors. Gateway routing (Phase 5) and Web UI (Phase 6) are future work.
To verify the new config section parses:
🤖 Generated with Claude Code